import { Meta } from '@storybook/addon-docs';

<Meta title="Dev/Analytics" />

# Analytics

Here there is every analytics (Sentry, Heap, etc.) related info.

## Legend

### [Sentry](https://sentry.io/)

The tool of choice to

- Track uncaught JavaScript errors in the Console
- Track uncaught React errors in the Console
- Track errors sent back by the server
- Track custom events as errors (or warnings or logs, see `programmaticallyTraceError`)

it can be enabled through the `HASURA_CONSOLE_SENTRY_DSN` environment variable. At the time of writing, Hasura enables it only for the Cloud Console.

### [Heap](https://heap.io/)

The tool of choice to

- Track the usage of the Console's features
- Create funnels out of it
- Identify if features that include heavy legacy code or dependencies can be removed

## The `<Analytics />` component

`<Analytics />` is the central reference for everything analytics related. It covers 99% of the use cases, but the `@features/Analytics` module also exposes the underlying `useGetAnalyticsAttributes` and `getAnalyticsAttributes`. Where to use them? Well

|                                                                                                                                                      | `<Analytics />`                                   | `useGetAnalyticsAttributes` | `getAnalyticsAttributes` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------- | ------------------------ |
| Do you need to add the HTML attributes to DOM elements?                                                                                              | ✅                                                |                             |                          |
| Do you need to add the HTML attributes to React components?                                                                                          | ✅                                                |                             |                          |
| Do you need to add the HTML attributes to React components that accept custom HTML attributes (like `<Button />`)?                                   | ✅ (with the `passHtmlAttributesToChildren` prop) |                             |                          |
| Do you need to add the HTML attributes to DOM elements that cannot be wrapped in React components? (ex. the `title` tag passed to Helmet)            |                                                   | ✅                          |                          |
| Do you need to use the Analytics features from a React Class component?                                                                              |                                                   |                             | ✅                       |
| Do you wou want to embed the analytics features in a common component (like `<Dialog />`)? (please consider decoupling the two functionalities, BTW) | ✅                                                |                             |                          |
| Do want to avoid conditionally the `<Analytics />` component?                                                                                        |                                                   | ✅                          |                          |

Following, a list of features `<Analytics />` unleashes.

### data-analytics-name

The custom `data-analytics-name` attributes are helpful for

1. Easing creating funnels by grouping related elements: creating funnels out of the displayed texts scales better, but, for instance, a button showing the text "Create" could be hard to be identified because the string "Create" could be present multiple times on the page. Instead, if the section containing the button has a `data-analytics-name="create-new-db"`, identifying the "Create" button becomes easier
2. Tracking elements whose contents are redacted because include sensitive data. Think about the database sidebar tree. All the items in the tree expose sensitive data but having the schema-related buttons with `data-analytics-name="sidebar-db-schewma"` and `data-analytics-name="sidebar-db-table"` allow tracking the clicks on them without leaking the database names

The `<Analytics />` component centralize adding the `data-analytics-name` attribute (enforced through an ESLint rule).

Please note: previously, we used the `data-trackid` attribute. Now, we consider it legacy.

### Sensitive data

The `<Analytics />` have batteries included to redact their text or HTML attributes that leak sensitive data.

Sensitive data’s importance:

1. Extremely important: secrets and environment variables - We must be 100% sure we do not leak this kind of data. The best way to ensure that must be explored yet, maybe [Heap's Visual Labeling](https://help.heap.io/definitions/visual-labeling/define-events-with-visual-labeling-web/) can help by identifying sensitive-data components in the UI, creating selectors out of them, and running a search in the past data.
2. Important: database names, table names, etc. - Avoid leaking them would be better off, but the importance is not the same as the prior point.

## The plan

Currently

- All the sections of the Console redact everything for Heap (see the usage of `<Analytics />`, you can verify it by opening the devtools and looking for the `data-analytics-name` attribute used at section-containers level, here is an example ![The Console showing a section with the data redaction attributes](./images/storybook-assets/analytics/section-data-redaction.jpg 'Data redaction at the section level')

## Custom events

Custom events are helpful to

- Track meaningful information about what the user is doing (e.g. "Disable the x-hasura-admin-secret key" instead of the standard "The user clicked on x-hasura-admin-secret" that is tracked automatically)
- Track interaction events for elements we do not control the rendered HTML (e.g. the GraphiQL component)
- Track interaction events for elements that are part of a parent that prevent Heap from tracing interaction events
- Track the server errors
- Track JavaScript-only information (e.g. the unexpected or outdated usage of a function)

Every time you add a custom event, think about what are the most suitable tool (even more than once) to track the event and copy/paste an existing tracing function instead of creating a new one with different patterns (look for the usage of the Analytics' `trackCustomEvent` function).
